Copyright

Connect ODBC for Oracle

© 2000 MERANT. All rights reserved.

DataDirect, INTERSOLV, Middleware, and SequeLink, are registered trademarks, and Client/Server MiddleWare, DataDirect Connect ADO, DataDirect Connect Integrator, DataDirect Connect JDBC, DataDirect Connect ODBC, DataDirect Connect OLE DB, DataDirect Connect Premium, DataDirect Reflector, DataDirect SequeLink Integrator, MERANT, and WebDBLink are trademarks of MERANT. All other trademarks are the property of their respective owners.


About Connect ODBC for Oracle

Connect ODBC for Oracle supports two separate drivers. Connect ODBC for Oracle (the "Oracle driver") supports the Oracle7 database system. The Oracle driver is supported in the Windows environments using the Oracle7 client.

Connect ODBC for Oracle8 (the "Oracle8 driver") supports the Oracle8 database system. It also supports the Oracle7 database system version 7.3.4 or higher when using the Oracle Net8 client.  The Oracle8 driver is supported in the Windows environments.

The Oracle driver file name is IVOR7nn.DLL, where nn is the revision level. The Oracle8 driver file name is IVOR8nn.DLL, where nn is the revision level.


Driver Requirements

Both Oracle and Oracle8 client information for Windows 9x, Windows NT, and Windows 2000 is listed below.

IMPORTANT: You must have all components of the Oracle client software installed; otherwise, the driver will not operate properly.

Oracle

The Oracle SQL*Net product is required to access remote Oracle7 databases. The appropriate DLLs for the current version of SQL*Net and OCIW32.DLL must be on your path. For example, SQL*Net 2.3 requires ORA73.DLL, CORE35.DLL, NLSRTL32.DLL, and CORE35O.DLL, as well as OCIW32.DLL.

Oracle8

The Oracle Net8 Client 8.0.4, or higher, is required to access remote Oracle8 databases (servers) 8.0.3 or higher. On Intel systems, the appropriate DLLs for the Oracle Net8 Client must be on your path, for example, ORA804.DLL, PLS804.DLL, and OCI.DLL.

The Oracle Net8 Client 8.0.4, or higher, is required to access remote Oracle databases (servers) 7.3.4.x.


Configuring Data Sources

On Windows, data sources are configured and modified through the ODBC Administrator. To configure an Oracle data source:

1	Start the ODBC Administrator to display a list of data sources.

2	If you are configuring an existing data source, select the data source name and click Configure to display the ODBC Oracle Driver Setup dialog box.

If you are configuring a new data source, click Add to display a list of installed drivers. Select the Oracle driver of your choice and click Finish to display the ODBC Oracle Driver Setup dialog box.

3	Specify a data source name, a server name and optionally, a description. Click Apply.

4	Click the Advanced tab to configure optional data source settings, such as packet size. Click Apply.

5	Click Translate to display the Select Translator dialog box, which lists the translators specified in the ODBC Translators section of the system information. DataDirect provides a translator named "OEM to ANSI" that translates your data from the IBM PC character set to the ANSI character set.

Select a translator, then click OK to close this dialog box and perform the translation.

6	Click Test Connect to attempt to connect to the data source using the connection properties specified in the Driver Setup dialog box.

7	Click OK or Cancel. If you click OK, the values you have specified become the defaults when you connect to the data source. You can change these defaults by using this procedure to reconfigure your data source. You can override these defaults by connecting to the data source using a connection string with alternate values.


Test Connection

At any point during the configuration process, you can click Test Connect to attempt to connect to the data source using the connection properties specified in the Driver Setup dialog box. A Logon dialog box is displayed. After providing connection information, click OK.

•	If the driver can connect, it releases the connection and displays a "connection established" message. Click OK.

•	If the driver cannot connect because of an improper environment or incorrect connection value, it will display an appropriate error message.

Verify that the all required client software is properly installed. If it is not, you will see the message:

Specified driver could not be loaded due to system error [xxx].

Click OK.


Connecting to Data Source Using a Logon Dialog
Connecting to a Data Source Using a Logon Dialog Box

Some ODBC applications display a logon dialog box when you are connecting to a data source. In these cases, the data source name has already been specified.

In the Logon dialog box, perform the following steps:

1	Type the client connection string of the computer containing the Oracle database tables you want to access or select the string from the Server Name drop-down list box, which displays the names you specified in the setup dialog box.

2	If required, type your Oracle user name.

3	If required, type your Oracle password.

4	Click OK to log on to the Oracle database installed on the server you specified and to update the values in the system information.

NOTE: Oracle has a feature that allows you to connect to Oracle via the operating system user name and password.  To connect, use a slash ( / ) for the user name and leave the password blank.  To configure the Oracle server/client, refer to the Oracle server documentation.


Connecting to Data Source Using a Connection String
Connecting to a Data Source Using a Connection String

If your application requires a connection string to connect to a data source, you must specify the data source name that tells the driver which section of the system information to use for the default connection information. Optionally, you may specify attribute=value pairs in the connection string to override the default values stored in the system information. These values are not written to the system information.

You can specify either long or short names in the connection string. The connection string has the form:

DSN=data_source_name[;attribute=value[;attribute=value]...]

An example of a connection string for Oracle is:

DSN=Accounting;SRVR=X:IVSRVR;UID=JOHN;PWD=XYZZY

If the server name contains a semicolon, enclose it in quotation marks:

DSN=Accounting;SRVR="X:IV;SRVR";UID=JOHN;PWD=XYZZY

The paragraphs that follow give the long and short names for each attribute, as well as a description. The defaults listed are initial defaults that apply when no value is specified in either the connection string or in the data source definition in the system information. If you specified a value for the attribute when configuring the data source, that value is the default.

ApplicationUsingThreads (AUT): ApplicationUsingThreads={0 | 1}. Ensures that the driver works with multi-threaded applications.

When set to 1 (the initial default), the driver is thread-safe.

When using the driver with single-threaded applications, you can set this option to 0 to avoid additional processing required for ODBC thread-safety standards.

Oracle7 only: When set to 1, SQLGetInfo(SQL_ASYNC_MODE) returns SQL_AM_NONE, SQLSetConnectAttr(SQL_ATTR_ASYNC_ENABLE) returns "optional feature not implemented," and SQLSet/GetStmtAttr(SQL_ATTR_ASYNC_ENABLE) returns "optional feature not implemented." Asynchronous execution is not supported by the Oracle client in a multi-threaded environment.

ArraySize (AS): The number of bytes the driver uses for fetching multiple rows. Values can be an integer from 1 up to 4 GB. Larger values increase throughput by reducing the number of times the driver fetches data across the network. Smaller values increase response time, as there is less of a delay waiting for the server to transmit data.

The initial default is 60,000.

CatalogOptions (CO): CatalogOptions={0 | 1}. Determines whether the result column REMARKS for the catalog functions SQLTables and SQLColumns and COLUMN_DEF for the catalog function SQLColumns have meaning for Oracle. If you want to obtain the actual default value, set CO=1.

The initial default is 0.

DataSourceName (DSN): A string that identifies an Oracle data source configuration in the system information. Examples include "Accounting" or "Oracle-Serv1."

EnableDescribeParam (EDP): EnableDescribeParam={0 | 1}. Determines whether the ODBC API function SQLDescribeParam is enabled, which results in all parameters being described with a data type of SQL_VARCHAR.

This attribute should be set to 1 when using Microsoft Remote Data Objects (RDO) to access data.

The initial default is 0.

EnableStaticCursorsForLongData (ESCLID): EnableStaticCursorsForLongData={0 | 1}. Determines whether the driver supports long columns when using a static cursor. Using this attribute causes a performance penalty at the time of execution when reading long data.

The initial default is 0.

LockTimeOut (LTO) ): LockTimeOut={0 | -1}. Determines whether Oracle should wait for a lock to be freed before raising an error when processing a Select...For Update statement.

When set to 0, Oracle does not wait.

When set to -1 (the initial default), Oracle waits forever.

LogonID (UID): The default logon ID (user name) that the application uses to connect to your Oracle database. A logon ID is required only if security is enabled on your database. If so, contact your system administrator to get your logon ID. To use your operating system user name, see Connecting to a Data Source Using a Logon Dialog Box.

OptimizeLongPerformance (OLP) Oracle8 only: OptimizeLongPerformance={0 | 1}. Determines whether the driver fetches long data directly into the application’s buffers rather than allocating buffers and making a copy.

When set to 0 (the initial default), the driver allocates buffers for long data.

When set to 1, using this setting, the driver fetches long data directly into the application’s buffers. The time an application takes to fetch long data decreases; however, it can cause the application to be limited to one active statement per connection.

PacketSize (PS) Oracle7 only: PacketSize={1024 | 2048 | 4096 | 8192}. Determines the packet size for TCP/IP connections. Any values other than 1024, 2048, 4096, or 8192 are ignored. This value is used only when the ServerName attribute (described later) is set to T for TCP/IP.

Password (PWD): The password that the application uses to connect to your Oracle database. To use your operating system password, see Connecting to a Data Source Using a Logon Dialog Box.

ProcedureRetResults (PRR): ProcedureRetResults={0 | 1}. Determines whether the driver returns result sets from stored procedure functions.

When set to 0 (the initial default), the driver does not return result sets from stored procedures.

When set to 1, the driver returns result sets from stored procedures. When set to 1 and you execute a stored procedure that does not return result sets, you will incur a small performance penalty. See Stored Procedure Results for details.

ServerName (SRVR): The client connection string that designates the server and database to be accessed. The information required varies depending on the client driver that you are using.

For Oracle7 remote servers, the SQL*Net 1.x connection string has the following syntax:

driver_prefix:computer_name[:sid]

driver_prefix identifies the network protocol being used. The driver prefix can be as follows: P (named pipes), X (SPX), B (NetBIOS), T (TCP/IP), D (DECNet), A (Oracle Async), or AT (AppleTalk). Check your Oracle documentation for other protocols.

computer_name is the name of the Oracle Listener on your network.

sid is the Oracle System Identifier and refers to the instance of Oracle running on the host. This item is required when connecting to systems that support more than one instance of an Oracle database.

For local servers, the SQL*Net connection string has the form:

database_name

database_name identifies your Oracle database.

If the SQL*Net connection string contains semicolons, enclose it in quotation marks. See your SQL*Net documentation for more information.

For Oracle7 and Oracle8 remote servers, the Oracle TNS Client connection string has the following form:

TNSNAME

TNSNAME is the alias name of the Oracle Listener on your network.

UseCurrrentSchema (UCS): UseCurrentSchema={0 | 1}. Determines whether the driver specifies only the current user when executing SQLProcedures.

When set to 0,the driver does not specify only the current user.

When set to 1 (the initial default), the call for SQLProcedures is optimized, but only procedures owned by the user are returned.


Data Types

The following table shows how the Oracle data types are mapped to the standard ODBC data types.

Oracle	ODBC
Char	SQL_CHAR
Date	SQL_TYPE_TIMESTAMP
Long	SQL_LONGVARCHAR
Long Raw	SQL_LONGVARBINARY
Number	SQL_DOUBLE
Number(p,s)	SQL_DECIMAL
Raw	SQL_VARBINARY
Varchar2	SQL_VARCHAR
Oracle8

The following table shows how, when connecting to Oracle8 servers, the following additional Oracle8 data types are mapped to the standard ODBC data types. These data types support output parameters to stored procedures.

Oracle8	ODBC
Bfile	SQL_LONGVARBINARY*
Blob	SQL_LONGVARBINARY
Clob	SQL_LONGVARCHAR
* Read-Only

The Oracle8 driver does not support any Abstract Data Types. When the driver encounters an Abstract Data Type during data retrieval, it will return an Unknown Data Type error (SQL State HY000).


Stored Procedure Results

When the connection option Procedure Returns Results is active, the driver returns result sets from stored procedures/functions. In addition, SQLGetInfo(SQL_MULT_RESULTS_SETS) will return "Y" and SQLGetInfo(SQL_BATCH_SUPPORT) will return SQL_BS_SELECT_PROC. If this option is on and you execute a stored procedure that does not return result sets, you will incur a small performance penalty.

This feature requires that stored procedures be in a certain format.  First, a package must be created to define all of the cursors used in the procedure, then the procedure can be created using the new cursor. For example:

Create or replace package GEN_PACKAGE as

CURSOR G1 is select CHARCOL from GTABLE2;

type GTABLE2CHARCOL is ref cursor return G1%rowtype;

end GEN_PACKAGE;

Create or replace procedure GEN_PROCEDURE1 (

  rset IN OUT GEN_PACKAGE.GTABLE2

  CHARCOL, icol INTEGER) as

begin

   open rset for select CHARCOL from GTABLE2

     where INTEGERCOL <= icol order by INTEGERCOL;

end;

When executing the stored procedures with result sets, do not include the result set arguments in the list of procedure arguments.  The previously described example would be executed as:

{call GEN_PROCEDURE1 (?)}

where ? is the parameter for the icol argument.

For more information consult your Oracle SQL manual.


Isolation and Lock Levels Supported

Oracle supports isolation level 1 (read committed) and isolation level 3 (serializable isolation—if the server version is Oracle7.3 or higher, or Oracle8.x). Oracle supports record-level locking.


ODBC Conformance Level

The API functions supported are listed in “Supported ODBC Functions,” found in the General Help section of Connect ODBC Help.

The Oracle drivers also support the following functions:

•	SQLColumnPrivileges

•	SQLDescribeParam (if EnableDescribeParam=1)

•	SQLForeignKeys

•	SQLPrimaryKeys

•	SQLProcedures

•	SQLProcedureColumns

•	SQLSetPos

•	SQLTablePrivileges

The drivers support the core SQL grammar.


Number of Connections and Statements Supported

The Oracle drivers support multiple connections and multiple statements per connection.


General Tab, ODBC Oracle Driver Setup

Use the ODBC Oracle Driver Setup dialog box to create new Oracle data sources or configure existing data sources.

Data Source Name: Type a string that identifies this Oracle data source configuration in the system information. Examples include "Accounting" or "Oracle-Serv1."

Description: Type an optional long description of a data source name. For example, "My Accounting Database" or "Oracle on Server number 1."

Server Name: Type the client connection string designating the server and database to be accessed. The information required varies depending on the client driver you are using. See the ServerName option described in Connecting to Oracle Using a Connection String for the format of the client connection string.

Advanced Tab

Displays the Advanced tab, where you can configure optional data source settings, such as packet size.

OK

Cancel

Apply

Test Connect


Advanced Tab, ODBC Oracle Driver Setup

Use the Advanced tab on the ODBC Oracle Driver Setup dialog box to specify optional settings when you create new Oracle data sources or configure existing data sources.

Server List: Type a list of client connection strings that will appear in the logon dialog box. Separate the strings with commas. If the client connection string contains a comma, enclose it in quotation marks; for example, "Serv,1", "Serv,2", "Serv,3."

Default User Name: Type the default user name used to connect to your Oracle database. A default user name is required only if security is enabled on your database. Your ODBC application may override this value or you may override this value in the logon dialog box or connection string.

Array Size: Type the number of bytes the driver uses for fetching multiple rows. Values can be an integer from 1 up to 4 GB; the default is 60000. Larger values increase throughput by reducing the number of times the driver fetches data across the network. Smaller values increase response time, as there is less of a delay waiting for the server to transmit data.

Lock Timeout: Select a value of 0 or -1 that specifies whether Oracle should wait for a lock to be freed before raising an error when processing a Select...For Update statement. Values can be -1 (wait forever) or 0 (do not wait). The default is -1.

Packet Size (Oracle7 only): Select a value that controls the packet size for TCP/IP connections. Specify one of the following packet sizes: 1024, 2048, 4096, or 8192. Any other value is ignored.

The Packet Size option is used only when the connection string specified in the Server Name option is T for TCP/IP as the driver prefix. See the ServerName option described in Connecting to Oracle Using a Connection String for the format of the client connection string.

Catalog Options: Select this check box if you want the result column REMARKS for the catalog functions SQLTables and SQLColumns, and the result column COLUMN_DEF for the catalog function SQLColumns to have meaning for Oracle. Selecting this box reduces the performance of your queries. By default, the check box is not selected, which returns SQL_NULL_DATA for the result columns COLUMN_DEF and REMARKS.

Enable SQLDescribeParam: Select this check box to enable the SQLDescribeParam function, which results in all parameters being described with a data type of SQL_VARCHAR. This option should be selected when using Microsoft Remote Data Objects (RDO) to access data. By default, the check box is not selected.

Application Using Threads: Select this check box to ensure that the driver works with multi-threaded applications. When using the driver with single-threaded applications, clear this check box. Turning off this setting avoids additional processing required for ODBC thread-safety standards. By default, the check box is selected.

Oracle7 only: When Application Using Threads is enabled, SQLGetInfo(SQL_ASYNC_MODE) returns SQL_AM_NONE, SQLSetConnectAttr(SQL_ATTR_ASYNC_ENABLE) returns "optional feature not implemented," and SQLSet/GetStmtAttr(SQL_ATTR_ASYNC_ENABLE) returns "optional feature not implemented." Asynchronous execution is not supported by the Oracle client in a multi-threaded environment.

Procedure Returns Results: Select this check box to enable the driver to return result sets from stored procedures/functions. If this check box is selected and you execute a stored procedure that does not return result sets, you will incur a small performance penalty.See Stored Procedure Results. By default, this check box is not selected.

Enable Static Cursors for Long Data: Select this check box to enable the driver to support long columns when using a static cursor. Selecting this check box causes a performance penalty at the time of execution when reading long data. By default, the check box is not selected.

Use Current Schema for SQLProcedures: Select this check box to specify only the current user when executing SQLProcedures. When this ckeck box is selected (the default), the call for SQLProcedures is optimized, but only procedures owned by the user are returned.

Optimize Long Performance (Oracle8 only): Select this check box to fetch long data directly into the application’s buffers rather than allocating buffers and making a copy. This option, when enabled, decreases fetch times on long data; however, it can cause the application to be limited to one active statement per connection. By default, the check box is not selected.

Translate Button

Displays the Select Translator dialog box, where you can translate your data from one character set to another. Choose the "OEM to ANSI" translator to translate your data from the IBM PC character set to the ANSI character set.

OK

Cancel

Apply

Test Connect


Logon to Oracle Dialog
Logon to Oracle Dialog Box

Server Name: Type the client connection string of the computer containing the Oracle database tables you wish to access, or select the string from the Server Name drop-down list, which displays the names you specified in the ODBC Oracle Driver Setup dialog box.

User Name: If required, type your Oracle user name.

Password: If required, type your Oracle password.

NOTE: Oracle has a feature that allows you to connect to Oracle via the operating system user name and password.  To connect, use a slash ( / ) for the user name and leave the password blank.  To configure the Oracle server/client, refer to the Oracle server documentation.


Apply Button

Writes the settings you have specified to the system information. These settings remain in effect until you change them in this dialog box. Clicking Cancel does not affect settings that have been applied.


OK Button

Writes the settings you have specified to the system information and closes the dialog box.


Cancel Button

Closes the dialog box without saving settings that have not been applied.


Contacting Technical Support

MERANT provides technical support for all registered users of this product, including limited installation support, for the first 30 days. For support after that time, contact us using one of the following methods or purchase further support by enrolling in the SupportNet program. For more information about SupportNet, contact your sales representative.

The MERANT Web site provides the latest support information through SupportNet Online, our global service network that provides access to valuable tools and information. Our SupportNet users access information using the Web, automatic email notification, newsgroups, and regional user groups. SupportNet Online includes a knowledge base that allows you to search on keywords for technical bulletins and other information. You also can download product fixes for your DataDirect products.

World Wide Web

http://support.merant.com

E-Mail

USA, Canada, and Mexico	datadirect.answerline@merant.com
Australia and New Zealand	australia.answerline@merant.com
Japan	jpn.answerline@merant.co.jp
All other countries	int.datadirect.answerline@merant.com
Local Telephone Support

Local phone numbers can be found at http://support.merant.com/websupport/contact/supportnetanswerline.asp.

Live Answerline telephone support is available 24 hours a day, seven days a week.

Fax and Mail Information

Fax US	1 919 461 4527
Fax Int.	+32 (0) 15 32 09 19
Mail	1500 Perimeter Park Drive, Suite 100, Morrisville, NC 27560 USA

Information to Provide

When you contact us, please include this information:

•	The product serial number located on the Product Registration Information card or on a product serial number card in your package. The number will be checked to verify your support eligibility. If you do not have a SupportNet contract, we will ask you to speak with a sales representative.

•	Your name and organization. For a first-time call, you may be asked for full customer information, including location and contact details.

•	The version number of your DataDirect product.

•	The type and version of your operating system.

•	Any third-party software or other environment information required to understand the problem.

•	A brief description of the problem, including any error messages that you have received, and the steps preceding the occurrence of the problem. Depending on the complexity of the problem, you may be asked to submit an example so that we can recreate the problem.

•	An assessment of the severity level of the problem.


Unicode Support

The Oracle drivers determine that the Oracle database is a unicode database if the NLS_LANG environment variable is set to either:

•	AMERICAN_AMERICA.UTF8

•	AMERICAN_AMERICA.AL24UTFFSS

Both of the Oracle drivers map the Oracle data types as follows:

Oracle Data Type	Mapped to. . .
Char	SQL_WCHAR
Varchar2	SQL_WVARCHAR
Long	SQL_WLONGVARCHAR
CLOB data types are not supported.

These drivers support the Unicode ODBC function calls, called W (Wide) calls (for example, SQLConnectW). These calls are used to accept Unicode datastreams.

Default Unicode Mapping

The default Unicode mapping for an application’s SQL_C_WCHAR variable is:

Platform	Default Unicode Mapping
Windows	UCS-2
AIX	UTF-8
HP-UX	UTF-8
Solaris	UTF-8
Linux	UTF-8
Connection Attributes for Unicode

Two new connection attributes are available to support Unicode. These attributes determine how character data is converted and presented to an application and the database. The connection attributes are:

SQL_ATTR_APP_WCHAR_TYPE (1061)	Sets the SQL_C_WCHAR type for parameter and column binding to the desired unicode type, either SQL_DD_CP_UCS2 or SQL_DD_CP_UTF8. The default is the default Unicode mapping (see the previous section).
SQL_ATTR_DBMS_WCHAR_TYPE (1062)	Sets the code page type of the database. The main purpose of this attribute is to set the code page type of a database for drivers that cannot determine the database’s code page. The default is SQL_DD_CP_ANSI.
Valid values for the two connection attributes are:

•	SQL_DD_CP_ANSI (ANSI code page)

•	SQL_DD_CP_UCS2 (UCS-2 code page)

•	SQL_DDO_CP_UTF8 (UTF-8 code page)

You can set these connection attributes either before or after a connection is made. If the connection attributes are changed after a connection is established, all conversions use the new values.

The driver does not verify that the connection attributes are set only once per connection. Conversions are made based on the current application and database settings.

If the application does not set the SQL_ATTR_DBMS_CODE_PAGE attribute, the driver tries to determine the database’s code page type; if the driver cannot determine the code page type, the driver sets the SQL_ATTR_DBMS_CODE_PAGE attribute to SQL_DD_CP_ANSI. If the application does set the SQL_ATTR_DBMS_CODE_PAGE attribute, the driver, even if it can determine the database’s code page type, does not override the value of the attribute set by the application.

If a driver does not support Unicode, SQLGetConnect Attr and SQLSetConnectAttr return HYC00.

These new connection attributes and their valid values can be found in the file qesqlext.h, which is installed with the driver.


DTC Support
MTS Support

The Oracle8 driver can take advantage of Microsoft Transaction Server (MTS) capabilities, specifically, the Distributed Transaction Coordinator (DTC). Refer to the help file of the "MicroSoft Transaction Server SDK" for details. You must be accessing 8.0.4 or higher servers using Net8 Client 8.0.5.1.0 or higher.


Persisting a Result Set as an XML Data File

This driver allows you to persist a result set as an XML data file with embedded schema. To implement XML persistence, a client application must do the following:

1	Turn on STATIC cursors. For example:

SQLSetStmtAttr (hstmt, SQL_ATTR_CURSOR_TYPE, SQL_CURSOR_STATIC, SQL_IS_INTEGER)

2	Execute a SQL statement. For example:

SQLExecDirect (hstmt, "Select * from GTABLE", SQL_NTS)

3	Persist the result set as an XML data file. For example:

SQLSetStmtAttr (hstmt, SQL_PERSIST_AS_XML, "c:\temp\GTABLE.XML", SQL_NTS)

Note regarding Step 1: A result set can be persisted as an XML data file only if the result set is generated using STATIC cursors. Otherwise, the following error is returned:

Driver only supports XML persistence when using driver’s static cursors.

Note regarding Step 3: A new statement attribute is available to support XML persistence, SQL_PERSIST_AS_XML. A client application must call SQLSetStmtAttr with this new attribute as an argument. See the following table for the definition of valid arguments for SQLSetStmtAttr.

Argument	Definition
StatementHandle	The handle of the statement that contains the result set to persist as XML.
Attribute	SQL_PERSIST_AS_XML. This new statement attribute can be found in the file qesqlext.h, which is installed with the driver.
ValuePtr	Pointer to a URL that specifies the full path name of the XML data file to be generated. The directory specified in the path name must exist, and if the specified file name exists, the file will be overwritten.
StringLength	The length of the string pointed to by ValuePtr or SQL_NTS if ValuePtr points to a null terminated string.

A client application can choose to persist the data at any time that the statement is in an executed or cursor-positioned state. At any other time, the driver will return the following message:

Function Sequence Error